%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{2018/10/26}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpcviewer}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{hpcviewer:\\ Interactive Presentation of Performance}

The Java-based \Prog{hpcviewer} interactively presents program performance in a top-down fashion.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Synopsis}

Command-line usage:\\
\SP\SP\SP\Prog{hpcviewer} \oOpt{options} \oOpt{hpctoolkit-database}

GUI usage:\\
\SP\SP\SP Launch \File{hpcviewer} and open the experiment database \oOpt{hpctoolkit-database}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

The Java-based \Prog{hpcviewer} interactively presents program-performance experiment databases
in a top-down fashion.
Since experiment databases are self-contained,
they may be relocated from a cluster for visualization on a laptop or workstation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arguments}

\begin{Description}
\item[\Arg{hpctoolkit-database}] An HPCToolkit experiment database
produced by \Prog{hpcprof} or \Prog{hpcprof-mpi}.
\end{Description}


\subsection{Options}

\begin{Description}

\item[\Opt{-consolelog}]
Send log entries to a console in addition to a log file.

\item[\Opt{-debug}]
Log additional information about plugin dependency problems.

\end{Description}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Detailed Description}

\subsection{Views}

\Prog{hpcviewer} supports three principal views of an application's performance data.
Each view reports both inclusive costs (including callees) and exclusive costs (excluding callees).

\begin{itemize}

\item \textbf{Calling context view.}
A top-down view depicting the dynamic calling contexts (call paths) in which costs were incurred.
With this view one can explore the performance of an application in a top-down manner
to understand the costs incurred by calls to a procedure in a particular calling context.

\item \textbf{Callers view.}
This bottom-up view enables one to look upward along call paths.
It apportions a procedure's costs to its caller and, more generally,
its calling contexts.
This view is particularly useful for understanding the performance of software components or procedures
that are used in more than one context.

\item \textbf{Flat view.}
This view organizes performance data according to the static structure of an application.
All costs incurred in \emph{any} calling context by a procedure are aggregated together in the flat view.

\item \textbf{Thread view}
	This view is to display the metrics of a certain threads (or processes) named Thread View, if the datababe is generated by \texttt{hpcprof-mpi}.
To activate the view, one needs to select a thread or a set of threads of interest.
To select a single thread, one can click on the dot from the plot graph.
Then click the context menu ``Show thread X'' to activate the thread view.

To select a group of threads, use the thread selection window by clicking the thread-view button from the calling-context view.
On the thread selection window, one needs to select the checkbox of the threads of interest. 
To  narrow the list, one can specify the thread name on the filter part of the window.
Recall that the format of the thread is ``\texttt{process\_id . thread\_id}''.
Hence, to specify just a main thread (thread zero), one can type '.0' on the filter, and the view only list threads 0 (such as 1.0, 2.0, 3.0).

Once threads have been selected, click \textbf{OK}, and the Thread view will be activated. 
The tree of the view is the same as the tree from calling context view, with the metrics only from the selected threads.
If there are more than one selected threads, the metrics are the average of the values of the selected threads.


\end{itemize}


\subsection{Panes}

The browser window is split into three panes:

\begin{itemize}

\item \textbf{Source pane.} The source pane appears at the top of the browser window
and displays source code associated with the current selection in the navigation pane below.
Making a selection in the navigation pane causes the source pane
to display the selection's corresponding source file and highlight the source line.

\item \textbf{Navigation pane.}
The navigation pane appears at the bottom left of the browser window
and displays an outline (tree structure) organizing the performance measurements under investigation.
Each item in the outline denote a structure in the source code such as a
load module, source file, procedure, procedure activation,
loop, single line of code, or code fragment inlined from elsewhere.
Outline items can be selected and their children folded and unfolded.

Which items appear in the outline depend on which view is displayed: 

\begin{itemize}

\item In the calling context view, displayed items are
procedure activations, loops, source lines, and inlined code. 
Most items link to a single location in the source code,
but a procedure activation item links to two:
the call site where the procedure was invoked and the procedure body executed in response.

\item In the callers view, displayed items are always procedure activations.
Unlike the calling context view, where a call site is paired with its called procedure,
in this view a call site is paired with its calling procedure,
attributing costs for a called procedure among all its call sites (and therefore callers).

\item In the flat view, displayed items are
source files, call sites, loops, and source lines.
Call sites are rendered in the same way as procedure activations.

\end{itemize}

The header above the navigation pane contains buttons for adjusting the displayed view:

\begin{itemize}

\item \textbf{Up arrow.} \emph{Zoom in} to show only information for the selected line and its descendants.

\item \textbf{Down arrow.} \emph{Zoom out} to reverse a previous zoom-in operation.

\item \textbf{Hot path}. Toggle hot path mode,
which automatically unfolds subitems along the \emph{hot path} for the currently selected metric:
those subitems encountered by starting at the selected item
and repeatedly descending to the child item with largest cost for the metric.
This is an easy way to find performance bottlenecks for that metric.

\item \textbf{Derived metric}. Define a new metric in terms of existing metrics
by entering a spreadsheet-style formula.

\item \textbf{Filter metrics}. Show or hide specified metrics.

\item \textbf{CSV export}. Write data from the current view to a file
in standard CSV (Comma Separated Values) format.

\item \textbf{Bigger text}. Increase the size of displayed text.

\item \textbf{Smaller text}. Decrease the size of displayed text.

\item \textbf{Showing graph of metric values}.
Showing the graph (plot, sorted plot or histogram) of metric values of the selected node in CCT for all processes or threads.
This menu is only available if the database is generated by \texttt{hpcprof-mpi} instead of \texttt{hpcprof}. 

\item \textbf{Show the metrics of a set of threads}.
Showing the CCT and the metrics of a seletected threads.
This menu is only available if the database is generated by \texttt{hpcprof-mpi} instead of \texttt{hpcprof}. 
 


\item \textbf{Flatten} (icon of a slashed tree node).
\emph{Flatten} the navigation pane outline,
i.e. replace each top-level item by its child subitems
(available in flat view only).
If an item has no children it remains in the outline.
Flattening may be performed repeatedly, each step hiding another level of the outline.
This is useful for relaxing the strict hierarchical view
so that peers at the same level in the tree can be viewed and ranked together.
For instance, this can be used to hide procedures in the flat view
so that outermost loops can be ranked and compared.

\item \textbf{Unflatten.} Undo one previous flatten operation (flat view only).

\end{itemize}

\item  \textbf{Metric pane.}
The metric pane appears to the right of the navigation pane at the bottom of the window
and displays one or more columns of performance data, one metric per column.
Each row displays measured metric values for the source structure denoted by the outline item to its left.
A metric may be selected by clicking on its column header,
causing outline items at each level of the hierarchy to be sorted by their values for that metric.

\end{itemize}


\subsection{Thread-Centric Graphs}

\Prog{hpcviewer} can display graphs of thread-level metric values.
This is useful for quickly assessing load imbalance across processes and threads.

To create a graph,
choose the calling context view and select an item in the navigation pane,
then pop up the context menu by right-clicking the item.
A list of graphable metrics appears at the bottom of the context menu,
each with a sub-menu showing the three graph styles that \Prog{hpcviewer} can make.
The \emph{Plot} graph displays metrics by MPI rank and thread number;
The \emph{Sorted plot} graph displays metrics sorted by value;
and the \emph{Histogram} graph displays a barchart of metric value distributions.

Note: graphs are currently available only for databases created by \Prog{hpcprof-mpi}
(but not by \Prog{hpcprof}).
See \emph{Plotting Graphs of Thread-level Metric Values} in the User's Manual
for details and sample graphs.



% ===========================================================================
% ===========================================================================

\section{Menus}

\Prog{hpcviewer} provides five main menus:

% ==========================================================
% ==========================================================

\subsection{File}
This menu includes several menu items for controlling basic viewer operations.
\begin{itemize}
\item \textbf{New window}
  Open a new \Prog{hpcviewer} window that is independent from the existing one.

\item \textbf{Open database...}
  Load a performance database into the current \Prog{hpcviewer} window. 
Currently \Prog{hpcviewer} restricts maximum of five database open at a time. 
If you want to display more than five, either you close an existing open database first, or you open a new \Prog{hpcviewer} window.

\item \textbf{Close database...}
  Unloading one of more open performance database.

\item \textbf{Merge database CCT.../Merge database flat tree...}
  Merging two database that are currently in the viewer. If \Prog{hpcviewer} has more than two
open database, then you need to choose which database you want to merge.

Currently \Prog{hpcviewer} does not support storing a merged database into a file.

\item \textbf{Preferences...}
  Display the settings dialog box.

\item \textbf{Close window}
  Closing the current window. If there is only one window, then this menu will also exit \Prog{hpcviewer} application.

\item \textbf{Exit}
  Quit the \Prog{hpcviewer} application.

\end{itemize}

% ==========================================================
% ==========================================================

\subsection{Filter}
This menu only contains one submenu:
\begin{itemize}
 \item \textbf{Show filter property}
  Open a filter property window which lists a set of filters and its properties.
\Prog{hpcviewer} allows  users to define multiple filters, and each filter is associated with a type and a glob pattern (A glob pattern specifies which name to be removed by using wildcard characters such as *, ? and +).
There are three types of filter: ``\textbf{self only}'' to omit matched nodes, 
``\textbf{descendants only}'' to exclude only the subtree of the matched nodes, and ``\textbf{self and descendants}'' to
remove matched nodes and its descendants.

\end{itemize}

% ==========================================================
% ==========================================================

\subsection{View}
This menu is only visible if at least one database is loaded.
All actions in this menu are intended primarily for tool developer use. 
By default, the menu is hidden. Once you open a database, the menu is then shown.

\begin{itemize}
 \item \textbf{Show views}
 Display all the list of views (calling context views, callers view and flat view) for each database. If a view was closed, it will be suffixed by a "\texttt{*closed*}" sign and can be reactivated by double-clicking the name of the view in the tree.

 \item \textbf{Show metric properties}
 Display a list of metrics in a window. From this window, you can modify the name of the metric. For derived metrics, this also allows to modify the formula as well as the format.

 \item \textbf{Debug}
 A special set of menus for advanced users. These menus are useful to debug \Prog{hpcviewer}. The menu consists of:

   \begin{itemize}
     \item \textbf{Show database raw's XML}
 	Enable one to request display of raw XML representation for performance data.

     \item \textbf{Show CCT label}
 	Display calling context ID for each node in the tree. This option is important to match between the node tree in hpcviewer with the data in experiment.xml.

     \item \textbf{Show flat label}
 	Display static ID for each node in the tree.
  \end{itemize}

\end{itemize}
% ==========================================================
% ==========================================================

\subsection{Window}
This menu contains only one submenu to reset the position of the views to the original default position.
Since \Prog{hpcviewer} is built on top of Eclipse, sometimes Eclipse fails to reposition its views due to its bugs.
A work-around to fix this issue is an ongoing work.

% ==========================================================
% ==========================================================

\subsection{Help}

This menu displays information about the viewer. The menu contains two items:
\begin{itemize}

\item \textbf{About}.
  Displays brief information about the viewer, including used plug-ins and error log.

\end{itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\section{Examples}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\section{Notes}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2019, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

\noindent
Rice University's HPCToolkit Research Group \\
Email: \Email{hpctoolkit-forum =at= rice.edu} \\
WWW: \URL{http://hpctoolkit.org}.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:

